home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER21.TXT < prev    next >
Text File  |  1995-05-29  |  13KB  |  356 lines
  1.                             Miscellaneous Routines
  2.  
  3.                                       "You yourself are much condemned
  4.                                       to have an itching palm; to sell
  5.                                       and mart your offices for Gold."
  6.  
  7.                                         Shakespeare, Julius Caesar IV.3
  8.  
  9. Introduction
  10.  
  11.           The GoldMISC unit contains a grab-bag of miscellaneous
  12.      procedures and functions that really do not call for an entire unit
  13.      of their own. They may, one day, grow up and have their own units.
  14.      Some of these routines were developed to support other units, and
  15.      may be of little value to you on a regular basis. Nonetheless, they
  16.      are here if you need them. The routines are organized into three
  17.      categories: File, Printer and Misc.
  18.  
  19. File Routines
  20.  
  21.      FSize(Filename:string): longint;
  22.  
  23.           Returns a longint indicating the size of the file in bytes. If
  24.           the FileName passed is not found, a -1 value is returned.
  25.  
  26.      FileDrive(Full:string): string;
  27.  
  28.           Extracts and returns the drive letter (without the colon) from
  29.           a filename. If the passed string parameter does not include a
  30.           drive, a null is returned, i.e. ''.
  31.  
  32.      FileExt(Full:string): string;
  33.  
  34.           Extracts the file extension (excluding the period) from a
  35.           filename. If the passed string parameter does not include an
  36.           extension, a null is returned, i.e. ''.
  37.  
  38.      FileDirectory(Full:string): string;
  39.  
  40.           Extracts the directory path (without the drive letter) from a
  41.           filename. If the passed string parameter does not include an
  42.           extension, a null is returned, i.e. ''. The trailing backslash
  43.           is always removed.
  44.  
  45.      FileName(Full:string): string;
  46.  
  47.           Extracts the file name (excluding the extension) from a
  48.           filename. If the passed string parameter does not include an
  49.           extension, a null is returned, i.e. ''.
  50.  
  51.      SlashedDirectory(Dir:string):string;
  52.  
  53.           This function is useful for building fully-qualified
  54.           filenames. The passed directory name is returned, with a
  55.           backslash added if the string did not already terminate with a
  56.           backslash or colon.
  57.  
  58.      ParentDirectory(Dir:string): string;
  59.  
  60.           Returns the name of the parent to the directory string passed.
  61.           If only the root directory is passed then the root is
  62.           returned. A null string is returned if the string passed does
  63.           not contain a parent.
  64.  
  65.      SmartMakeDir(DirectStr: PathStr): integer;
  66.  
  67.           Parses the passed string and creates each subdirectory as it
  68.           progresses. The final product is a newly created (or nested)
  69.           subdirectory. The passed string must follow the DOS naming
  70.           conventions. Failures are recorded in  LastMiscError.
  71.  
  72.      Exist(Filename:string):boolean;
  73.  
  74.           Returns true if the filename can be found. The passed string
  75.           must follow all the DOS naming conventions.
  76.  
  77.      DeleteFile(Filename:string): shortint;
  78.  
  79.           Designed to delete the filename passed, this function returns
  80.           a shortint value indicating the results of the routine, as
  81.           follows:
  82.  
  83.                -1 - File not found
  84.                 0 - File deleted {success}
  85.                 1 - Error - file not deleted.
  86.  
  87.      RenameFile(Oldname,NewName:string):shortint;
  88.  
  89.           Attempts to rename the old filename to the new filename.
  90.           Returns a shortint value indicating the results, as follows:
  91.  
  92.                0 - File renamed {success}
  93.                1 - File not found
  94.                2 - Rename failed
  95.  
  96.      CopyFile(SourceFile, TargetFile:string): shortint;
  97.  
  98.           Copies a file like the DOS copy command. If a file with the
  99.           same name as the Target already exists, it will be
  100.           overwritten. The function returns one of the following byte
  101.           values:
  102.  
  103.                0 - Successful
  104.                1 - Source and Target are the same
  105.                2 - Cannot open source
  106.                3 - Unable to create target
  107.                4 - Error during copy
  108.  
  109. Printer Routines
  110.  
  111.      The GoldMISC unit includes the following printer related routines:
  112.  
  113.      PrinterStatus:byte;
  114.  
  115.           This function is designed to indicate whether or not a
  116.           parallel printer is attached and on-line. The global variable
  117.           MiscVARS.LPTport indicates which port to test. Set
  118.           MiscVARS.LPTport to 0 for LPT1 (default), 1 for LPT2, etc. The
  119.           function returns one of the following byte values to indicate
  120.           the status of the printer:
  121.  
  122.                0 - Printer ready
  123.                1 - No paper
  124.                2 - Off line
  125.                3 - Busy
  126.                4 - Undetermined error
  127.  
  128.      AlternatePrinterStatus:byte;
  129.  
  130.           This function is very similar in operation to PrinterStatus
  131.           but uses a slightly different technique. If you have problems
  132.           using PrinterStatus with some weirdo printer, try this
  133.           function instead.
  134.  
  135.      PrinterReady :boolean;
  136.  
  137.           This function returns true if a printer is detected as being
  138.           on-line and ready.
  139.  
  140.      PrintScreen;
  141.  
  142.           This procedure emulates the user pressing the PrtScr key, and
  143.           dumps the visible display to the printer port.
  144.  
  145.      ResetPrinter;
  146.  
  147.           This procedure should reset any printer back to its default
  148.           (boot-up) settings.
  149.  
  150. Memory Info
  151.  
  152.           It is not a good idea to use every scrap of available memory
  153.      on the heap, as your program will tend to be unstable. Also, with
  154.      no memory left, it is difficult to display information to the user
  155.      advising him/her of the low memory.
  156.  
  157.           The GoldMISC unit includes a longint variable,
  158.      MiscVARS.GoldMemBuffer, with a default value of 10,000 bytes. This
  159.      represents the amount of memory which will be left free when Gold
  160.      routines try to allocate memory on the heap. You may change the
  161.      value as necessary.
  162.  
  163.           The following functions should be used in preference to
  164.      MemAvail and MaxAvail:
  165.  
  166.      GoldMaxAvail:longint;
  167.  
  168.           After deducting the amount of memory reserved by
  169.           MiscVars.GoldMemBuffer, this routine returns the size of the
  170.           largest contiguous amount of free memory.
  171.  
  172.      GoldMemAvail:longint;
  173.  
  174.           After deducting the amount of memory reserved by
  175.           MiscVars.GoldMemBuffer, this routine returns the total amount
  176.           of free memory.
  177.  
  178. Sounds
  179.  
  180.      The GoldMISC unit includes the following sound routines:
  181.  
  182.      Beep;
  183.  
  184.           You guessed! This function emits a brief, but nonetheless
  185.           irritating, beep from the PC speaker.
  186.  
  187.      Ding;
  188.  
  189.           Teensy Weensy little noise.
  190.  
  191.      Thunk;
  192.  
  193.           Somewhat negative sounding, like wrong key press.
  194.  
  195.      Trill;
  196.  
  197.           Great feedback. It indicates success.
  198.  
  199. Executing Other Programs
  200.  
  201.           The three routines listed below can be used to execute another
  202.      program or application from within the active application.
  203.  
  204.           IMPORTANT NOTE: You must use the $M compiler directive to
  205.      instruct Borland Pascal to leave some memory for the spawned or
  206.      child program, e.g.{$M $8192,$8192,$8192}. The precise values
  207.      depend on the size of your program, so experiment to determine the
  208.      optimum settings. If the child process runs OK, try smaller values.
  209.      If the child process doesn't run, try larger values.
  210.  
  211.      RunEXECOM(Progname, Params: string):integer;
  212.  
  213.           Executes an EXE or COM file as a child process. Pass two
  214.           parameters, the name of the program and the optional
  215.           parameters. Returns an integer value indicating the returned
  216.           DosError value; a zero indicates success.
  217.  
  218.      RunDOS(Msg:string):integer;
  219.  
  220.           Starts a secondary copy of COMMAND.COM. One parameter is
  221.           passed which is the message provided to the user. Returns an
  222.           integer value indicating the returned DosError value; a zero
  223.           indicates success.
  224.  
  225.      RunAnything(Command: string):integer;
  226.  
  227.           Spawns a child process from your application. Use this to run
  228.           non-executables such as batch files. Returns an integer value
  229.           indicating the returned DosError value; a zero indicates
  230.           success.
  231.  
  232. Development Tools
  233.  
  234.           If you look at any of the demo programs, you will find the
  235.      HeapRecord and HeapCheck routines used in each one. These routines
  236.      are designed to identify memory leaks in an application. If the
  237.      application finishes with less memory than when it started, an
  238.      error message is displayed. These routines were used extensively
  239.      during Gold's development!
  240.  
  241.           Memory leaks can occur, for example, when you forget to call
  242.      the function DisposeFields having created and used a form. When you
  243.      are developing applications, make it a habit to use these routines
  244.      to make sure that you have disposed of all memory you used.
  245.  
  246.      HeapRecord;
  247.  
  248.           Records the amount of available memory when the routine is
  249.           called. Call this procedure as the first statement in an
  250.           application.
  251.  
  252.      HeapCheck;
  253.  
  254.           Records the amount of available memory when the routine is
  255.           called and  compares it to the amount recorded by HeapRecord.
  256.           Differences are displayed on screen. Calling this routine
  257.           without first calling HeapRecord has no effect.
  258.  
  259.           Clearly you don't want these routines to be left in the
  260.      production code. If you have a memory leak in your application, you
  261.      certainly don't want your customer to see it! You should consider
  262.      placing these calls inside conditional defines. The following code
  263.      fragment illustrates this technique.
  264.  
  265.           begin
  266.           {$IFOPT D+}
  267.               HeapRecord;
  268.           {$ENDIF}
  269.               InitVars;
  270.               SetScreen;
  271.               SetFields;
  272.               MouseShow(true);
  273.               AssignHindHook(MyHindHook);
  274.               ProcessInput(1);
  275.               DisposeFields;
  276.               DisposeForms;
  277.               MouseShow(false);
  278.               clrscr;
  279.           {$IFOPT D+}
  280.               HeapCheck;
  281.           {$ENDIF}
  282.           end.
  283.  
  284. Miscellaneous
  285.  
  286.           Here are the routines that don't fit into any specific
  287.      category:
  288.  
  289.      GetBitStatus(B:byte;BitPos:byte): boolean;
  290.  
  291.           Returns the status of a single bit contained within a byte.
  292.           You store and retrieve up to 8 boolean values in a single
  293.           byte; these are numbered 0 through 7.
  294.  
  295.      SetBitStatus(var Val:byte; BitPos:byte; On:boolean);
  296.  
  297.           Used to change the value of a single bit within a byte.
  298.  
  299.      Swap(var A,B:longint);
  300.  
  301.           Switches the values of A and B.
  302.  
  303.      WithinRange(Min,Max,Test: longint): boolean;
  304.  
  305.           Determines whether or not the value contained in Test falls
  306.           between the upper and lower limits set in Min and Max and
  307.           returns an appropriate true or false value.
  308.  
  309.      GetMin(Value1,Value2:longint): longint;
  310.  
  311.           Returns the smallest of the two passed values.
  312.  
  313.      GetMax(Value1,Value2:longint): longint;
  314.  
  315.           Returns the largest of the two values passed.
  316.  
  317.      ParamLine: string;
  318.  
  319.           Returns the entire parameter line as a space-delimited string,
  320.           i.e. all the parameters specified by the user on the command
  321.           line when the application was executed.
  322.  
  323.      ParamVal(Marker:string): string;
  324.  
  325.           Searches for Marker in the command line and returns all
  326.           characters following the string up to the next occurrence of
  327.           the marker.
  328.  
  329.      Frequency(Match:string;Source:string): byte;
  330.  
  331.           Returns the number of times that Match occurs in Source.
  332.  
  333.      BadCharPos(Str:string): integer;
  334.  
  335.           This function is used for checking for invalid filename
  336.           characters in a string. The function returns the character
  337.           position of the first illegal character, or 0 if no illegal
  338.           characters were encountered.
  339.  
  340.      ValidFileName(FN:string): shortint;
  341.  
  342.           Verifies whether a filename is valid. Refer to the Reference
  343.           for a list of the possible return codes.
  344.  
  345.      LastMiscError: integer;
  346.  
  347.           Dealing with memory and DOS shells certainly leaves an
  348.           application open to failure. LastMiscError should be checked
  349.           regularly to determine whether the last call to a GoldMISC
  350.           function was successful.
  351.  
  352.  
  353.      El blanko pageo on purpuso
  354.  
  355.  
  356.